import "@site/src/languages/highlight";

# App

**Description:**

&emsp;&emsp;A record representing an application singleton instance.

## frame

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The current passed frame number.

**Signature:**
```tl
const frame: integer
```

## bufferSize

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The size of the main frame buffer texture used for rendering.

**Signature:**
```tl
const bufferSize: Size
```

## visualSize

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The logic visual size of the screen.
The visual size only changes when application window size changes.
And it won't be affacted by the view buffer scaling factor.

**Signature:**
```tl
const visualSize: Size
```

## devicePixelRatio

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The ratio of the pixel density displayed by the device
Can be calculated as the size of the rendering buffer divided by the size of the application window.

**Signature:**
```tl
const devicePixelRatio: number
```

## App.Platform

**Type:** Enumeration.

**Description:**

&emsp;&emsp;An enumerated type representing the platform the game engine is running on.

**Signature:**
```tl
enum Platform
	"Windows"
	"Android"
	"macOS"
	"iOS"
	"Linux"
	"Unknown"
end
```

## platform

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The platform the game engine is running on.

**Signature:**
```tl
const platform: Platform
```

## version

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The version string of the game engine.
Should be in format of "v0.0.0.0".

**Signature:**
```tl
const version: string
```

## deps

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The dependencies of the game engine.

**Signature:**
```tl
const deps: string
```

## deltaTime

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The time in seconds since the last frame update.

**Signature:**
```tl
const deltaTime: number
```

## elapsedTime

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The elapsed time since current frame was started, in seconds.

**Signature:**
```tl
const elapsedTime: number
```

## totalTime

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The total time the game engine has been running until last frame ended, in seconds.
Should be a contant number when invoked in a same frame for multiple times.

**Signature:**
```tl
const totalTime: number
```

## runningTime

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The total time the game engine has been running until this field being accessed, in seconds.
Should be a increasing number when invoked in a same frame for multiple times.

**Signature:**
```tl
const runningTime: number
```

## rand

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;A random number generated by a random number engine based on Mersenne Twister algorithm.
So that the random number generated by a same seed should be consistent on every platform.

**Signature:**
```tl
const rand: integer
```

## maxFPS

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;The maximum valid frames per second the game engine is allowed to run at.
The max FPS is being inferred by the device screen max refresh rate.

**Signature:**
```tl
const maxFPS: integer
```

## debugging

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;Whether the game engine is running in debug mode.

**Signature:**
```tl
const debugging: boolean
```

## testNames

**Type:** Readonly Field.

**Description:**

&emsp;&emsp;An array of test names of engine included C++ tests.

**Signature:**
```tl
const testNames: {string}
```

## locale

**Type:** Field.

**Description:**

&emsp;&emsp;The system locale string, in format like: `zh-Hans`, `en`.

**Signature:**
```tl
locale: string
```

## themeColor

**Type:** Field.

**Description:**

&emsp;&emsp;A theme color for Dora SSR.

**Signature:**
```tl
themeColor: Color
```

## seed

**Type:** Field.

**Description:**

&emsp;&emsp;A random number seed.

**Signature:**
```tl
seed: integer
```

## targetFPS

**Type:** Field.

**Description:**

&emsp;&emsp;The target frames per second the game engine is supposed to run at.
Only works when `fpsLimited` is set to true.

**Signature:**
```tl
targetFPS: integer
```

## fpsLimited

**Type:** Field.

**Description:**

&emsp;&emsp;Whether the game engine is limiting the frames per second.
Set `fpsLimited` to true, will make engine run in a busy loop to track the  precise frame time to switch to the next frame. And this behavior can lead to 100% CPU usage. This is usually common practice on Windows PCs for better CPU usage occupation. But it also results in extra heat and power consumption.

**Signature:**
```tl
fpsLimited: boolean
```

## idled

**Type:** Field.

**Description:**

&emsp;&emsp;Whether the game engine is currently idled.
Set `idled` to true, will make game logic thread use a sleep time and going idled for next frame to come. Due to the imprecision in sleep time. This idled state may cause game engine over slept for a few frames to lost.
`idled` state can reduce some CPU usage.

**Signature:**
```tl
idled: boolean
```

## fullScreen

**Type:** Field.

**Description:**

&emsp;&emsp;Whether the game engine is running in full screen mode.
It is not available to set this property on platform Android and iOS.

**Signature:**
```tl
fullScreen: boolean
```

## alwaysOnTop

**Type:** Field.

**Description:**

&emsp;&emsp;Whether the game engine window is always on top.
It is not available to set this property on platform Android and iOS.

**Signature:**
```tl
alwaysOnTop: boolean
```

## winSize

**Type:** Field.

**Description:**

&emsp;&emsp;The application window size.
May differ from visual size due to the different DPIs of display devices.
It is not available to set this property on platform Android and iOS.

**Signature:**
```tl
winSize: Size
```

## winPosition

**Type:** Field.

**Description:**

&emsp;&emsp;The application window position.
It is not available to set this property on platform Android and iOS.

**Signature:**
```tl
winPosition: Vec2
```

## runTest

**Type:** Function.

**Description:**

&emsp;&emsp;A function that runs an specific C++ test included in the engine.

**Signature:**
```tl
runTest: function(self: App, name: string): boolean
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| name | string | The name of the test to run. |

**Returns:**

| Return Type | Description |
| --- | --- |
| boolean | Whether the test ran successfully. |

## openURL

**Type:** Function.

**Description:**

&emsp;&emsp;A function that opens a URL in the system default browser.

**Signature:**
```tl
openURL: function(self: App, url: string)
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| url | string | The URL to open. |

## install

**Type:** Function.

**Description:**

&emsp;&emsp;A function used for self updating the game engine.

**Signature:**
```tl
install: function(self: App, path: string)
```

**Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| path | string | The path to the new engine file. |

## shutdown

**Type:** Function.

**Description:**

&emsp;&emsp;A function that shuts down the game engine.
It is not working and acts as a dummy function for platform Android and iOS to follow the specification of how mobile platform applications should operate.

**Signature:**
```tl
shutdown: function(self: App)
```